<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>simvoc.core.kernel</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="simvoc-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            >SimVOC</th>
          </tr></table></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        <a href="simvoc-module.html">Package&nbsp;simvoc</a> ::
        <a href="simvoc.core-module.html">Package&nbsp;core</a> ::
        Module&nbsp;kernel
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
        <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
    onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
      </table>
    </td>
  </tr>
</table>
<!-- ==================== MODULE DESCRIPTION ==================== -->
<h1 class="epydoc">Module kernel</h1><p class="nomargin-top"><span class="codelink"><a href="simvoc.core.kernel-pysrc.html">source&nbsp;code</a></span></p>
<p>This module implements the core components of the SimVOC kernel, 
  including the main Simulator class and output handler base class.</p>
  <h1 class="heading">Application Notes:</h1>
    <ol start="1">
      <li>
        Simulator objects do NOT automatically timestamp results. If event 
        time is desired in the results, then the return value from the 
        action's run method should somehow encode the timestamp (e.g. 
        return a string containing the timestamp).
      </li>
      <li>
        Event functions CAN add new events to the simulation, but the time 
        for such events must NOT be earlier than the current clock time 
        (i.e. events cannot be scheduled in the past). A 
        TimeTravelException will occur in such cases.
      </li>
      <li>
        Multiple events CAN be scheduled to occur at the same time. 
        However, this simulator is purely sequential: there is no parallel 
        execution of events that would occur at the same time. Hence, this 
        simulator CANNOT be used to detect possible race conditions in 
        concurrent operations. Furthermore, while events are partially 
        ordered with respect to time, there is no guarantee of activation 
        order when two or more events occur at the same clock interval.
      </li>
      <li>
        Events fall into two categories: &quot;regular&quot; and 
        &quot;periodic&quot;. There is nothing special about regular 
        events, except that they have their &quot;keepalive&quot; flags set
        to True. Periodic events have &quot;keepalive&quot; set to False, 
        allowing has_regular_events to return False if only periodic events
        are left in the queue. This design permits simulator client code to
        make calls to has_regular_events to determine if another periodic 
        event should be scheduled.
      </li>
      <li>
        The simulator stops whenever its event queue becomes empty. Thus, 
        client code should stop adding events whenever it is ready to 
        terminate. Unchecked periodic functions that re-schedule themselves
        WILL result in infinite simulation runs.
      </li>
      <li>
        Time units are integers or floating-point numbers. The temporal 
        meaning of a time (e.g. seconds, minutes, etc.) depends on the 
        application.
      </li>
      <li>
        The simulator core is NOT thread-safe. It is intended for use 
        within a single thread only.
      </li>
      <li>
        If an event returns a *list* or a regular *tuple*, then the 
        list/tuple will be forwarded whole to the output handler (i.e. 
        there will be a single result entry containing the entire 
        list/tuple). To return multiple results (which will be sent to the 
        output object as separate results), return a 1-tuple containing a 
        list or tuple, e.g. ([1, 2, 3],)
      </li>
      <li>
        The output handler consists of a pipeline containing one or more 
        instances of the Output class or any of its subclasses. Output data
        may be filtered by writing subclasses that perform desired data 
        selection actions.
      </li>
      <li>
        Simulator objects provide a random source (using the Python random 
        module) for use by client code. This random source may be seeded at
        Simulator instantiation time, so that simulation results are 
        repeatable.
      </li>
      <li>
        The simulator contains an internal debugging mechanism to assist 
        with client code debugging. This mechanism is by default set to 
        suppress debugging messages unless and until a large number 
        (default 10,000) of consecutive event loop iterations occur, in 
        which only periodic events are found in the queue. Since automatic 
        detection of infinite simulations is not possible (halting 
        problem), this heuristic may be adjusted or disabled as desired.
      </li>
    </ol>

<!-- ==================== CLASSES ==================== -->
<a name="section-Classes"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Classes</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Classes"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="simvoc.core.kernel.TimeTravelException-class.html" class="summary-name">TimeTravelException</a><br />
      Exception raised when attempting to schedule an event in the past
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="simvoc.core.kernel.Output-class.html" class="summary-name">Output</a><br />
      Simulator output handler base class.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="simvoc.core.kernel.StreamOutput-class.html" class="summary-name">StreamOutput</a><br />
      Writes output to a file-like object (default is sys.stdout).
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="simvoc.core.kernel.Event-class.html" class="summary-name">Event</a><br />
      Abstract representation of simulator events.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="simvoc.core.kernel.EventQueue-class.html" class="summary-name">EventQueue</a><br />
      Simulator event queue, implemented using the Python heapq module.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="simvoc.core.kernel.Simulator-class.html" class="summary-name">Simulator</a><br />
      Core Simulator class, which provides an event-driven discrete event
        simulation.
    </td>
  </tr>
</table>
<!-- ==================== FUNCTIONS ==================== -->
<a name="section-Functions"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Functions</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Functions"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">dict</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="simvoc.core.kernel-module.html#kernel_trace" class="summary-sig-name">kernel_trace</a>(<span class="summary-sig-arg">simtime</span>,
        <span class="summary-sig-arg">realtime</span>,
        <span class="summary-sig-arg">msg</span>,
        <span class="summary-sig-arg">qsize</span>,
        <span class="summary-sig-arg">events</span>,
        <span class="summary-sig-arg">rate</span>,
        <span class="summary-sig-arg">de</span>,
        <span class="summary-sig-arg">dq</span>)</span><br />
      Base function that produces a dictionary with kernel trace data 
      (time, queue size, event counts, etc.) at each kernel update 
      interval.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="simvoc.core.kernel-pysrc.html#kernel_trace">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">dict</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="simvoc.core.kernel-module.html#kernel_metadata" class="summary-sig-name">kernel_metadata</a>(<span class="summary-sig-arg">start_time</span>,
        <span class="summary-sig-arg">end_time</span>,
        <span class="summary-sig-arg">exec_time</span>,
        <span class="summary-sig-arg">event_count</span>,
        <span class="summary-sig-arg">event_rate</span>)</span><br />
      Base function that creates a metadata dictionary at the end of a 
      simulation run.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="simvoc.core.kernel-pysrc.html#kernel_metadata">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
</table>
<!-- ==================== VARIABLES ==================== -->
<a name="section-Variables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Variables</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Variables"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="__package__"></a><span class="summary-name">__package__</span> = <code title="'simvoc.core'"><code class="variable-quote">'</code><code class="variable-string">simvoc.core</code><code class="variable-quote">'</code></code>
    </td>
  </tr>
</table>
<p class="indent-wrapped-lines"><b>Imports:</b>
  <span title="heapq">heapq</span>,
  <span title="os">os</span>,
  <span title="random">random</span>,
  <span title="sys">sys</span>,
  <span title="time">time</span>
</p><br />
<!-- ==================== FUNCTION DETAILS ==================== -->
<a name="section-FunctionDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Function Details</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-FunctionDetails"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
</table>
<a name="kernel_trace"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">kernel_trace</span>(<span class="sig-arg">simtime</span>,
        <span class="sig-arg">realtime</span>,
        <span class="sig-arg">msg</span>,
        <span class="sig-arg">qsize</span>,
        <span class="sig-arg">events</span>,
        <span class="sig-arg">rate</span>,
        <span class="sig-arg">de</span>,
        <span class="sig-arg">dq</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="simvoc.core.kernel-pysrc.html#kernel_trace">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Base function that produces a dictionary with kernel trace data (time,
  queue size, event counts, etc.) at each kernel update interval. This 
  function may be replaced by simulation system client code as desired.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>simtime</code></strong> (number) - Current simulated time</li>
        <li><strong class="pname"><code>realtime</code></strong> (float) - Current wall clock time in UTC seconds since the epoch</li>
        <li><strong class="pname"><code>msg</code></strong> (str) - Current simulator message</li>
        <li><strong class="pname"><code>qsize</code></strong> (int) - Current event queue size</li>
        <li><strong class="pname"><code>events</code></strong> (int) - Total number of events processed</li>
        <li><strong class="pname"><code>rate</code></strong> (float) - Event processing rate (events/sec)</li>
        <li><strong class="pname"><code>de</code></strong> (int) - Number of events processed since last trace update</li>
        <li><strong class="pname"><code>dq</code></strong> (int) - Change in event queue size since last trace update</li>
    </ul></dd>
    <dt>Returns: dict</dt>
        <dd>dictionary containing trace information</dd>
  </dl>
</td></tr></table>
</div>
<a name="kernel_metadata"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">kernel_metadata</span>(<span class="sig-arg">start_time</span>,
        <span class="sig-arg">end_time</span>,
        <span class="sig-arg">exec_time</span>,
        <span class="sig-arg">event_count</span>,
        <span class="sig-arg">event_rate</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="simvoc.core.kernel-pysrc.html#kernel_metadata">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Base function that creates a metadata dictionary at the end of a 
  simulation run. Client code may replace this function if desired.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>start_time</code></strong> (float) - Simulation start time in UTC seconds since epoch</li>
        <li><strong class="pname"><code>end_time</code></strong> (float) - Simulation end time in UTC seconds since epoch</li>
        <li><strong class="pname"><code>exec_time</code></strong> (float) - Execution time (seconds) for the simulation</li>
        <li><strong class="pname"><code>event_count</code></strong> (int) - Total number of events processed during the run</li>
        <li><strong class="pname"><code>event_rate</code></strong> (float) - Average event processing rate over the run</li>
    </ul></dd>
    <dt>Returns: dict</dt>
        <dd>dictionary containing simulator metadata</dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="simvoc-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            >SimVOC</th>
          </tr></table></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0 on Fri Oct 23 11:04:28 2009
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>
